home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / bru.z / bru
Text File  |  1998-10-20  |  42KB  |  859 lines
  1.  
  2.  
  3.  
  4. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      bru - backup and restore utility
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      bbbbrrrruuuu mmmmooooddddeeeessss [ ccccoooonnnnttttrrrroooollll ooooppppttttiiiioooonnnnssss ] [ sssseeeelllleeeeccccttttiiiioooonnnn ooooppppttttiiiioooonnnnssss ] files
  13.  
  14. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  15.      _B_r_u is a UUUUNNNNIIIIXXXX filesystem backup utility with significant enhancements
  16.      over other more common utilities such as _t_a_r, _c_p_i_o, _v_o_l_c_o_p_y, and _d_d.
  17.      Some of _b_r_u's capabilities include:
  18.  
  19.           o  Full or incremental backup with quick and easy restoration of
  20.              files.
  21.           o  Multiple physical volumes per archive.
  22.           o  Data integrity assurance via checksum computation on every
  23.              archive block.
  24.           o  Ability to properly save and restore directories, symbolic links,
  25.              block special files, and character special files.
  26.           o  Comparison of archives with current directory hierarchy.
  27.           o  Ability to recover files from corrupted archives or damaged media
  28.              with minimal data loss.
  29.           o  No inherent maximum archive buffer size.
  30.           o  Improved performance through random access archive I/O when
  31.              available.
  32.           o  Automatic byte or half word swapping as necessary when reading
  33.              archives produced on other machines.
  34.           o  Recognition of filename generation patterns in the same form as
  35.              the shell for files read from an archive.
  36.  
  37.      When _f_i_l_e_s are specified on the command line then the actions to be
  38.      performed are limited to those _f_i_l_e_s.  If a named file is a directory
  39.      then it and all its descendents are used.  If no _f_i_l_e_s are specified then
  40.      the default for writing archives is all files in and below the current
  41.      directory.  The default for reading archives is selection of all files in
  42.      the archive.
  43.  
  44.      If ``-'' is given instead of _f_i_l_e_s then the standard input is read to
  45.      obtain the file list.  This is useful in conjunction with the _f_i_n_d
  46.      command to provide finer control over files selected for backup.
  47.      Obviously this mode is only valid when _b_r_u is not also reading its
  48.      archive from the standard input.
  49.  
  50.      If you are doing backups non-interactively (for example, via _c_r_o_n, be
  51.      sure to read the description of the ----BBBB option below.
  52.  
  53. DDDDEEEEFFFFAAAAUUUULLLLTTTTSSSS
  54.      Various default parameters, such as archive device name and size, archive
  55.      buffer size, controlling terminal name, etc.  are system dependent.
  56.      These defaults, along with version, variant, and other miscellaneous
  57.      internal  information may be discovered via the ----hhhh mode.
  58.  
  59.      _b_r_u assumes the default tape device to be ////ddddeeeevvvv////ttttaaaappppeeee if no tape device is
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  71.  
  72.  
  73.  
  74.      specified using the ----ffff option.  For this to work correctly, ////ddddeeeevvvv////ttttaaaappppeeee
  75.      should be linked to the actual tape device, for ex.  ////ddddeeeevvvv////mmmmtttt////ttttppppssss0000dddd6666.... Also
  76.      there should be an appropriate entry for ////ddddeeeevvvv////mmmmtttt////ttttppppssss0000dddd6666 in the
  77.      ////eeeettttcccc////bbbbrrrruuuuttttaaaabbbb file.
  78.  
  79. MMMMOOOODDDDEEEESSSS
  80.      One or more of the following modes must be specified.  The order of
  81.      execution, from highest priority to lowest, is eeeecccciiiittttxxxxddddgggghhhh.
  82.  
  83.      ----cccc        CCCCrrrreeeeaaaatttteeee a new archive.  Forces a new archive to be created
  84.                regardless of whether one currently exists.  Writing starts at
  85.                the first block.
  86.  
  87.      ----dddd        DDDDiiiiffffffffeeeerrrreeeennnncccceeeessss between archived _f_i_l_e_s and current _f_i_l_e_s are
  88.                detected and reported.  May be specified more than once, as ----dddddddd
  89.                ----dddddddddddd or ----dddddddddddddddd to control level of difference checking.
  90.  
  91.                When specified as ----dddd _b_r_u reports when it discovers that a
  92.                regular file's size (st_size) or contents (when compared as
  93.                byte streams) has changed since the archive was made.
  94.  
  95.                When specified as ----dddddddd _b_r_u reports additional differences in
  96.                modification date (st_mtime) access mode (st_mode), number of
  97.                links (st_nlink) for non-directory files, differences in the
  98.                contents of symbolic links, owner id (st_uid), and group id
  99.                (st_gid).
  100.  
  101.                When specified as ----dddddddddddd _b_r_u reports additional differences in
  102.                host device (st_dev), major/minor device (st_rdev) for special
  103.                files, and time of last access (st_atime) for regular files.
  104.  
  105.                When specified as ----dddddddddddddddd _b_r_u reports all differences except time
  106.                of last status change (st_ctime is not resettable), major/minor
  107.                device numbers for non-special files (meaningless), and size
  108.                differences for directory files (may have empty entries).  The
  109.                ----dddddddddddddddd mode is generally only meaningful during a verification
  110.                pass with full backups of quiescent filesystems.
  111.  
  112.      ----eeee        EEEEssssttttiiiimmmmaaaatttteeee media requirements for archive creation with same
  113.                arguments.  Prints estimated number of volumes, number of files
  114.                to be archived, total number of archive blocks, and total size
  115.                of archive in kilobytes.  If the media size is unknown,
  116.                unspecified, or set to 0 via the ----ssss flag or the _b_r_u_t_a_b file, it
  117.                is assumed to be infinite.  The ----ZZZZ flag may also be given.  If
  118.                used, every file that would be backed up will be compressed to
  119.                a temporary file, which may slow down the estimation
  120.                considerably.  When ----ZZZZ,----cccc and ----eeee are all used, each file will
  121.                be compressed twice, once during the estimation pass, and once
  122.                while writing to the archive.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  137.  
  138.  
  139.  
  140.      ----gggg        Dump archive info block in a form more easily parsed by
  141.                programs implementing a complete filesystem management package.
  142.                Performs no other archive actions.  Note: when used with ----tttt,
  143.                and the rewind tape device, this information is printed after
  144.                the file list.  This option will not work when used with ----tttt if
  145.                the norewind tape device is used, since _b_r_u expects to be
  146.                positioned at the beginning of the tape archive after the tape
  147.                device is closed.  When a number of _b_r_u archives are written to
  148.                the same tape, a sequence like that below will work correctly
  149.                (where # is the position of a particular archive set), listing
  150.                first the label information, and then the files in the same
  151.                archive.
  152.  
  153.                mt fsf #
  154.                bru -vgf /dev/nrtape
  155.                mt bsf 1
  156.                bru -vtf /dev/nrtape
  157.  
  158.  
  159.      ----hhhh   Print hhhheeeellllpppp summary of options.  Also prints some internal
  160.           information such as version number and default values for archive
  161.           pathname, media size, archive buffer size, etc.
  162.  
  163.      ----iiii   IIIInnnnssssppppeeeecccctttt archive for internal consistency and data integrity.  When
  164.           ----vvvvvvvv option is also given, prints information from archive header
  165.           block.
  166.  
  167.      ----tttt   List ttttaaaabbbblllleeee of contents of archive.  When used with the ----vvvv option
  168.           will give a verbose table of contents in the same format as the ``ls
  169.           -l'' command.  When used with the ----vvvvvvvv option will also indicate what
  170.           files are linked to other files, and where symbolic links point to.
  171.  
  172.      ----xxxx   EEEExxxxttttrrrraaaacccctttt named _f_i_l_e_s from archive.  If an archived file is extracted
  173.           (see ----uuuu option) then the access mode, device id (special files
  174.           only), owner uid, group uid, access time, and modification time are
  175.           also restored.  If the ----CCCC flag is given (see below), then the owner
  176.           uid and group uid will be changed to that of the current user.
  177.  
  178.           Nonexistent directories are recreated from archived directories if
  179.           possible, otherwise they are created with appropriate defaults for
  180.           the current user.  Extracted or created directories are initially
  181.           empty.
  182.  
  183. CCCCOOOONNNNTTTTRRRROOOOLLLL OOOOPPPPTTTTIIIIOOOONNNNSSSS
  184.      Many of the control options are similar in function to their _t_a_r or _c_p_i_o
  185.      equivalents.
  186.  
  187.      Sizes are specified in bytes.  The scale factors MMMM, kkkk, or bbbb, can be used
  188.      to indicate multiplication by 2**20, 1024, or 512 respectively.  Thus
  189.      ``10k'', ``20b'', and ``10240'' all specify the same number of bytes.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  203.  
  204.  
  205.  
  206.      ----aaaa   Do not update the aaaacccccccceeeessssssss times of disk files that have been read
  207.           while performing other actions.  Normally _b_r_u restores the access
  208.           and modification times of disk files after they have been read to
  209.           the access and modification times to whatever they were before the
  210.           read operation.  Restoring the times prevents defeat of the
  211.           mechanism used to track down and remove ``dead'' files that haven't
  212.           been accessed in any meaningful way recently.  Note that this has
  213.           the side effect that backup programs such as _d_u_m_p(1m) will backup
  214.           the file, since the _c_t_i_m_e of the file will have been modified; use
  215.           of ----aaaa is therefore recommended when using _d_u_m_p as your system backup
  216.           utility.  Use of ----aaaa will also slightly speed up backups, since the
  217.           inode will not be written.
  218.  
  219.      ----bbbb _b_s_i_z_e
  220.           Use _b_s_i_z_e as the archive input/output bbbbuuuuffffffffeeeerrrr size.  The minimum is
  221.           the size of an archive block (2k or 2048 bytes) and the maximum is
  222.           determined by available memory and I/O device limitations.  If _b_s_i_z_e
  223.           is not an even multiple of 2048 bytes, it will be rounded up.
  224.           Normally this option is only required with the ----cccc mode since _b_r_u
  225.           writes this information in the archive header block.  If specified,
  226.           _b_s_i_z_e overrides any existing default value (generally 20k), whether
  227.           built in or read from the archive header.
  228.  
  229.      ----BBBB   Useful in shell scripts where _b_r_u is run in the bbbbaaaacccckkkkggggrrrroooouuuunnnndddd with no
  230.           operator present or not possible, such as when there is no
  231.           controlling terminal, causing an open of ////ddddeeeevvvv////ttttttttyyyy to fail.  Under
  232.           these conditions, _b_r_u simply terminates with appropriate error
  233.           messages and status, rather than attempting interaction with the
  234.           terminal.  With this option, _b_r_u will exit, rather than try to open
  235.           the controlling terminal.  In this case, the entire backup must fit
  236.           on a single tape or other media, as there is no way to ask for a
  237.           media change.
  238.  
  239.      ----CCCC   Change the owner (cccchhhhoooowwwwnnnn) and group of each extracted file to the
  240.           owner uid and group gid of the current user.  Normally, _b_r_u will
  241.           restore the owner and group to those recorded in the archive.  This
  242.           flag causes bru to follow the system default, with extracted files
  243.           having the same owner and group as the user running _b_r_u, including
  244.           Root.
  245.  
  246.           The ----CCCC option is useful with archives imported from other systems.
  247.           In general, it should not be used by the operator or system
  248.           administrator when restoring saved files.  Use the ----ttttvvvv option to see
  249.           the owner and group of files stored in the archive.
  250.  
  251.      ----DDDD   This option is not implemented, but is still accepted for backward
  252.           compatibility with scripts that may use it.
  253.  
  254.      ----ffff _p_a_t_h
  255.           Use _p_a_t_h as the archive ffffiiiilllleeee instead of the default.  If the _p_a_t_h is
  256.           ``-'' then _b_r_u uses the standard input for archive reading or
  257.           standard output for archive writing, as appropriate.  If the path is
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  269.  
  270.  
  271.  
  272.           remote then it needs to be specified as [_u_s_e_r@]_s_y_s_t_e_m:/_d_e_v/???
  273.           The <user@> part of the path is optional, and if none is specified
  274.           then the user's login is used.  The login has to be equivalently
  275.           mapped to the remote machine if it has a password.
  276.  
  277.      ----FFFF   FFFFaaaasssstttt mode.  In fast mode, checksum computations and comparisons are
  278.           disabled.  This mode is useful when the output of one _b_r_u is piped
  279.           to the input of another _b_r_u, or when the data integrity of the
  280.           archive transmission medium is essentially perfect.  Archives
  281.           recorded with fast mode enabled must also be read with fast mode.
  282.           Also, be aware that some of the automatic features of _b_r_u, such as
  283.           automatic byte swapping, are not functional in fast mode.
  284.  
  285.      ----jjjj   Convert aaaabbbbssssoooolllluuuutttteeee pathnames to "."  relative pathnames.  This option
  286.           applies only to the ----xxxx mode.
  287.  
  288.      ----XXXX   Echo relative pathnames as absolute pathnames.  This option only
  289.           valid when used in conjunction with the -x, -j and -v options.
  290.  
  291.      ----LLLL _s_t_r
  292.           LLLLaaaabbbbeeeellll the archive with the specified string _s_t_r.  _S_t_r is limited to
  293.           63 characters and is usually some meaningful reminder pertaining to
  294.           the archive contents.
  295.  
  296.      ----llll   Ignore unresolved lllliiiinnnnkkkkssss.  Normally bru reports problems with
  297.           unresolved links (both regular and symbolic links).  This option
  298.           suppresses all such complaints.
  299.  
  300.      ----mmmm   Do not cross mmmmoooouuuunnnntttteeeedddd filesystem boundaries during expansion of
  301.           explicitly named directories.  This option applies only to
  302.           directories named in _f_i_l_e_s.  It limits selection of directory
  303.           descendents to those located on the same filesystem as the
  304.           explicitly named directory.  This option currently applies only to
  305.           the ----cccc and ----eeee modes.
  306.  
  307.      ----pppp   PPPPaaaassssssss over files in archive by reading rather than seeking.  Normally
  308.           _b_r_u will use random access capabilities if available.  This option
  309.           forces reading instead of seeks.
  310.  
  311.      ----RRRR   RRRReeeemmmmooootttteeee files are to be eeeexxxxcccclllluuuuddddeeeedddd from the archive (unless explicitly
  312.           listed on the command line; remote directories on the command line
  313.           are backed up as a directory, but files, subdirectories, etc.
  314.           therein will not be backed up).  Filesystems such as the _p_r_o_c(4)
  315.           filesystem are considered to not be local, based on the information
  316.           returned by the _s_t_a_t_v_f_s(2) system call.
  317.  
  318.      ----ssss _m_s_i_z_e
  319.           Use _m_s_i_z_e as the media ssssiiiizzzzeeee.  The effective media ssssiiiizzzzeeee will be
  320.           computed from _m_s_i_z_e since it must be integral multiple of the
  321.           input/output buffer size (see the ----bbbb option).  Normally this option
  322.           is only required with the ----cccc or ----eeee flags since _b_r_u writes this
  323.           information in the archive header block.  If specified, _m_s_i_z_e
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  335.  
  336.  
  337.  
  338.           overrides any existing default value, whether built in, read from
  339.           the _b_r_u_t_a_b file, or read from the archive header.  If set to 0, the
  340.           tape is assumed to be infinite in length, and the archive is written
  341.           until an error occurs, at which time a new volume is prompted for.
  342.  
  343.      ----vvvv   Enable vvvveeeerrrrbbbboooosssseeee mode.  May be specified more than once, as ----vvvvvvvv, ----vvvvvvvvvvvv,
  344.           or ----vvvvvvvvvvvvvvvv, to get even more verbosity.
  345.  
  346.      ----wwww   WWWWaaaaiiiitttt for confirmation.  _B_r_u will print the filename, the action to
  347.           be taken, and wwwwaaaaiiiitttt for confirmation.  Any response beginning with
  348.           'y' will cause the action to complete.  Any other response will
  349.           abort the action.
  350.  
  351.      ----ZZZZ   Use 12-bit LZW file compression.  This is not the default because
  352.           not all versions of _b_r_u know how to deal with compressed files.
  353.           When the ----vvvv option is also selected, the compression ratio for each
  354.           file is printed as a percentage.  When this flag is used in
  355.           conjunction with the ----tttt option on an archive that contains
  356.           compressed file, the actual archive file sizes and names are
  357.           printed, rather than the original values before archiving.  Files
  358.           are compressed into a temporary file in a directory given by the
  359.           BRUTMPDIR environment variable.  If not given, /usr/tmp is used.
  360.  
  361.      ----KKKK   Required to archive files larger than 2 Gigabytes.  _BBBB_rrrr_uuuu will issue a
  362.           warning and skip such files if the _----_KKKK flag is not specified.  Must
  363.           be used in conjunction with the _----_ZZZZ flag.  If _BBBB_rrrr_uuuu can compress the
  364.           file to a size smaller than 2 Gigabytes, the file will be archived.
  365.           Otherwise, a warning will be issued and the file will be skipped.
  366.  
  367. FFFFIIIILLLLEEEE SSSSEEEELLLLEEEECCCCTTTTIIIIOOOONNNN OOOOPPPPTTTTIIIIOOOONNNNSSSS
  368.      The file selection options control which files are selected for
  369.      processing.  Note that some options are only valid with specific modes.
  370.  
  371.      ----nnnn_d_a_t_e    Select only files nnnneeeewwwweeeerrrr than _d_a_t_e, where this is based on the
  372.                file modification time (see _ssss_tttt______mmmm_tttt_iiii_mmmm_eeee in _ssss_tttt_aaaa_tttt(2)); the inode
  373.                modification time is not checked.  The _d_a_t_e is given in one of
  374.                the forms:
  375.  
  376.                DD-MMM-YY[YY][,HH:MM:SS]   EX: 12-Mar-84,12:45:00
  377.                MM/DD/YY[YY][,HH:MM:SS]    EX: 3/12/84
  378.                MMDDHHMM[YY[YY]]           EX: 0312124584
  379.                pathname                   EX: /etc/lastfullbackup
  380.  
  381.                The time of day is optional in the first two forms.  If
  382.                present, it is separated from the date with a comma.  If YY is
  383.                less than 39, it is assumed to be in the range 2000-2039.
  384.                Otherwise, if less than 100, it is assumed to be in the range
  385.                1940-1999.  The resulting year must be in the range 1970-2038.
  386.  
  387.                If _d_a_t_e is really the pathname of a file, then the modification
  388.                date of that file will be used instead.  This is useful in
  389.                automated backups when a dummy file is ``touched'' to save the
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  401.  
  402.  
  403.  
  404.                date of last backup.
  405.  
  406.      ----oooo _u_s_e_r   Select only files oooowwwwnnnneeeedddd by _u_s_e_r.  _U_s_e_r may be specified in one
  407.                of three ways:
  408.  
  409.                     o  As an ascii string corresponding to a user name in the
  410.                        password file.
  411.                     o  As the pathname of a file in which case the owner of
  412.                        that file is used.
  413.                     o  As a numeric value (decimal).
  414.  
  415.      ----uuuu _f_l_a_g_s  When used in conjunction with ----xxxx mode, causes files of type
  416.                specified by _f_l_a_g_s to be uuuunnnnccccoooonnnnddddiiiittttiiiioooonnnnaaaallllllllyyyy selected regardless of
  417.                modification times.  Normally _b_r_u will not overwrite
  418.                (supersede) an existing file with an older archive file of the
  419.                same name.  Files which are not superseded will give warnings
  420.                if vvvveeeerrrrbbbboooosssseeee mode level 2 (----vvvvvvvv) or higher is enabled.  Possible
  421.                characters for _f_l_a_g_s are:
  422.  
  423.                     bbbb    select block special files
  424.                     cccc    select character special files
  425.                     dddd    select directories
  426.                     llll    select symbolic links
  427.                     pppp    select fifos (named pipes)
  428.                     rrrr    select regular files
  429.  
  430.                Selection of directories only implies that their attributes may
  431.                be modified.  Existing directories are never overwritten, this
  432.                option merely allows their attributes to be set back to some
  433.                previously existing state.
  434.  
  435.                Selection of symbolic links only implies that the contents of
  436.                the link will be modified.  It is currently impossible to
  437.                change access time, modification time, or the file mode of a
  438.                symbolic link.
  439.  
  440. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  441.      Create (----cccc) a new archive of all files under ``/usr/src'', writing
  442.      archive to file (----ffff) ``/dev/rmt0'' using multiple tapes with a maximum
  443.      size (----ssss) of 30 megabytes per tape.
  444.  
  445.           bru -c -f /dev/rmt0 -s 30M /usr/src
  446.  
  447.      Create (----cccc) a new archive on the default device in the first pass,
  448.      archiving all files in and below the current directory which have been
  449.      created or modified (----nnnn) since 3 P.M.  on 14-Jan-84.  Then do a second
  450.      pass to verify that there are no differences (----dddd) between the archive and
  451.      current files.  Each file is listed (----vvvv) as it is processed.
  452.  
  453.           bru -cvd -n 14-Jan-84,15:00:00
  454.  
  455.  
  456.  
  457.  
  458.  
  459.                                                                         PPPPaaaaggggeeee 7777
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  467.  
  468.  
  469.  
  470.      Archive all files owned (----oooo) by user ``user1'' using the default archive
  471.      device.
  472.  
  473.           find / -user user1 -print | bru -c -
  474.           bru -c -o user1 /
  475.  
  476.      Copy a directory hierarchy from ``/usr/u1'' to ``/usr/u2''.
  477.  
  478.           (cd /usr/u1; bru -cf - ) | (cd /usr/u2; bru -xf -)
  479.  
  480.      Extract (----xxxx) the regular file ``/usr/guest/myfile'' unconditionally (----uuuurrrr)
  481.      from an archive on file (----ffff) ``/dev/rf0''.  Since the device size was
  482.      recorded in the header block, it need not be specified.  Note that option
  483.      arguments do not need to be separated from their corresponding option
  484.      flag by whitespace.
  485.  
  486.           bru -x -ur -f/dev/rf0 ./usr/guest/myfile
  487.  
  488.      Extract (----xxxx) all C source files in ``/usr/src/cmd'' that have names
  489.      beginning with characters 'a' through 'm'.  Wait (----wwww) for confirmation
  490.      before extracting each file.
  491.  
  492.           bru -xw '/usr/src/cmd/[a-m]*.c'
  493.  
  494.      Inspect (----iiii) a previously created archive on the default device, dumping
  495.      the contents of the header block for inspection (----vvvvvvvvvvvv) and verifying
  496.      internal consistency and data integrity of the archive.
  497.  
  498.           bru -ivvv
  499.  
  500.      Back up the entire root filesystem without crossing mounted (----mmmm)
  501.      filesystem boundaries.  The archive will be written to file (----ffff)
  502.      ``/dev/rmt0'' using an I/O buffer size (----bbbb) of 10k bytes.
  503.  
  504.           cd /
  505.           bru -cvm -f /dev/rmt0 -b 10k
  506.  
  507. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  508.      Most diagnostics are reasonably informative.  The most common have to do
  509.      with meaningless combinations of options, incompatible options, hitting
  510.      memory or device limits, unresolved file links, trying to archive or
  511.      restore something to which access is normally denied, or problems with
  512.      media errors and/or archive corruption.
  513.  
  514. DDDDEEEEVVVVIIIICCCCEEEE TTTTAAAABBBBLLLLEEEE
  515.      _B_r_u contains an internal table of known devices and their
  516.      characteristics.  This table is dynamically loaded from a data file
  517.      specified by the environment variable BBBBRRRRUUUUTTTTAAAABBBB, or from /_e_t_c/_b_r_u_t_a_b, or
  518.      from an internal default description if neither of the preceding is
  519.      found.
  520.  
  521.  
  522.  
  523.  
  524.  
  525.                                                                         PPPPaaaaggggeeee 8888
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  533.  
  534.  
  535.  
  536.      The format of the _b_r_u data file for loadable devices is as follows.  Note
  537.      that the table MUST contain at least one entry and the first entry is the
  538.      default archive device.
  539.  
  540.      Also, the table should contain an entry for the standard input and
  541.      output, with a name of "-".
  542.  
  543.      Entries consist of a device name field, followed by one or more
  544.      capabilities fields.  Entries may span more than one line by escaping the
  545.      newline at the end of the line with a '\' character ('\' is last
  546.      character on line before newline).  All whitespace (tabs, blanks,
  547.      newlines, formfeeds) between fields is ignored.
  548.  
  549.      The device name field must be the first field in the entry and has the
  550.      following form:
  551.  
  552.           <device name>|<device name>| ... |<device name>
  553.  
  554.           example:  /dev/rmt[0-2]|/dev/mt[0-2]
  555.  
  556.      where each device has the same capabilities as the other devices
  557.      specified (a class of devices).  Regular expressions as described in
  558.      _r_e_g_e_x_p(3) may be used.
  559.  
  560.      Each capability field is of the form:
  561.  
  562.           <capability name>=<value>  or  <boolean flag>
  563.  
  564.           example:  size=640K   REOPEN  pwerr=EIO
  565.  
  566.      Note that there can be no whitespace between the capability name and the
  567.      value.  Note that a size of 0 is treated specially, see the ----ssss flag
  568.      description above.  Numeric values may be given in absolute form or with
  569.      a trailing scale factor of:
  570.  
  571.           b or B                  Blocks (512 bytes)
  572.           k or K                  Kilobytes (1024 bytes)
  573.           m or M                  Megabytes (1024 * 1024 bytes)
  574.  
  575.      Error numbers may be given in absolute or symbolic form, as defined in
  576.      <errno.h>.
  577.  
  578.      Currently used capabilities include:
  579.      Name       Type      Meaning
  580.      ______________________________________________________________________
  581.      size       numeric   media size in bytes if known, zero otherwise
  582.      seek       numeric   minimum seek resolution, zero if no seeks allowed
  583.      prerr      numeric   errno for partial reads
  584.      pwerr      numeric   errno for partial writes
  585.      zrerr      numeric   errno for zero reads
  586.      zwerr      numeric   errno for zero writes
  587.  
  589.  
  590.  
  591.                                                                         PPPPaaaaggggeeee 9999
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  599.  
  600.  
  601.  
  602.      frerr      numeric   errno for read of unformatted media
  603.      fwerr      numeric   errno for write of unformatted media
  604.      wperr      numeric   errno for write protected media
  605.      reopen     boolean   close and reopen archive upon media switch
  606.      noreopen   boolean   no close and reopen archive upon media switch
  607.      tape       boolean   archive device is a tape drive
  608.      rawtape    boolean   archive device is a "raw" tape drive
  609.                           used primarily with devices that support
  610.                           multiple block sizes
  611.      norewind   boolean   closing does not automatically rewind
  612.      advance    boolean   read/writes advance media even when errors occur
  613.  
  614.      For instance, an excerpt from /_e_t_c/_b_r_u_t_a_b for SCSI tapedrives is:
  615.  
  616.      /dev/r*mt/tps[0-9]d[1-7]nr* \
  617.              size=0K seek=0 \
  618.              prerr=EIO pwerr=EIO zrerr=ENOSPC zwerr=ENOSPC frerr=0 fwerr=0 \
  619.              wperr=EROFS norewind reopen tape rawtape advance
  620.      #
  621.      /dev/r*mt/tps[0-9]d[1-7]* \
  622.              size=0K seek=0 \
  623.              prerr=EIO pwerr=EIO zrerr=ENOSPC zwerr=ENOSPC frerr=0 fwerr=0 \
  624.              wperr=EROFS reopen tape rawtape advance
  625.      #       This entry is a generic entry for stdin and stdout.
  626.      - size=0 seek=0 prerr=0 pwerr=0 zrerr=0 zwerr=0 frerr=0 fwerr=0 wperr=0
  627.  
  628.      The internal table that is used if no file can be found is:
  629.  
  630.  
  631.      /dev/tape* \
  632.              size=0k seek=0 \
  633.              prerr=EIO pwerr=EIO zrerr=ENOSPC zwerr=ENOSPC frerr=0 fwerr=0 \
  634.              wperr=EROFS reopen tape rawtape advance
  635.      /dev/nrtape* \
  636.              size=0k seek=0 \
  637.              prerr=EIO pwerr=EIO zrerr=ENOSPC zwerr=ENOSPC frerr=0 fwerr=0 \
  638.              wperr=EROFS norewind reopen tape rawtape advance
  639.  
  640.  
  641. SSSSIIIIGGGGNNNNAAAALLLL HHHHAAAANNNNDDDDLLLLIIIINNNNGGGG
  642.      _B_r_u normally catches both interrupt (SIGINT) and quit (SIGQUIT).  When
  643.      interrupt is caught during archive creation or extraction, _b_r_u completes
  644.      its work on the current file before cleaning up and exiting.  This is the
  645.      normal way of aborting _b_r_u.  When a quit signal is caught an immediate
  646.      exit is taken.
  647.  
  648.      Note that during file extraction, a quit signal may leave the last file
  649.      only partially extracted.  Similarly, a quit signal during archive
  650.      writing may leave the archive truncated.  When either interrupt or quit
  651.      is caught at any other time an immediate exit is taken.
  652.  
  653.  
  654.  
  655.  
  656.  
  657.                                                                        PPPPaaaaggggeeee 11110000
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  665.  
  666.  
  667.  
  668. EEEERRRRRRRROOOORRRR RRRREEEECCCCOOOOVVVVEEEERRRRYYYY
  669.      When properly configured for a given software/hardware environment, bru
  670.      can recover from most common errors.  For example, attempts to use
  671.      unformatted media are detected, allowing substitution of formatted media.
  672.      Random blocks in an archive can be deliberately overwritten (corrupted)
  673.      without affecting _b_r_u's ability to recover data from the rest of the
  674.      archive.  When I/O errors are detected, retries are performed
  675.      automatically.  Out of order sequencing on multi-volume archive reads is
  676.      detected, allowing replacement with the correct volume.
  677.  
  678. DDDDIIIIRRRREEEECCCCTTTTOOOORRRRIIIIEEEESSSS
  679.      When creating non-incremental archives _b_r_u automatically archives all
  680.      directories necessary to fully restore any file from the archive.  During
  681.      extraction, any required directories which do not already exist are
  682.      restored from the archive if possible, otherwise they are created with
  683.      appropriate defaults for the current user.
  684.  
  685.      The net result is that restoration from incremental archives (which may
  686.      not contain all necessary directories), or incremental restoration from
  687.      full archives (which may skip directories needed later), may result in
  688.      creation of directories with the default attributes.
  689.  
  690. WWWWIIIILLLLDDDDCCCCAAAARRRRDDDDSSSS
  691.      When rrrreeeeaaaaddddiiiinnnngggg archives _b_r_u recognizes filename generation patterns in the
  692.      same format as the shell.  This allows greater flexibility in specifying
  693.      files to be extracted, compared, or listed.  As a special extension to
  694.      shell type expansion, the sense of the match is reversed for patterns
  695.      that begin with '!'.
  696.  
  697.      Note that the patterns may have to be quoted to prevent expansion by the
  698.      shell.  Also note that patterns are processed independently, without
  699.      regard for any other patterns that may or may not be present.  In
  700.      particular, "/bin/a*  /bin/b*" is equivalent to "/bin/[ab]*", but
  701.      "/bin/!a* /bin/!b*" is equivalent to "/bin/*", nnnnooootttt "/bin/![ab]*".
  702.  
  703. BBBBYYYYTTTTEEEE////WWWWOOOORRRRDDDD SSSSWWWWAAAAPPPPPPPPIIIINNNNGGGG
  704.      While reading archives produced on other machines, _b_r_u automatically
  705.      attempts to perform byte and/or word swapping as necessary.
  706.  
  707.      If no device table is specified, _b_r_u automatically uses the no-swap tape
  708.      device, which provides higher performance and compatibility with non-byte
  709.      swapped tapes from other systems.  The IRIS 3000 series does not support
  710.      non-byte swapped tapes, but the automatic byte-swapping capabilities of
  711.      _b_r_u will deal with this problem.
  712.  
  713. RRRREEEEMMMMOOOOTTTTEEEE TTTTAAAAPPPPEEEE DDDDRRRRIIIIVVVVEEEESSSS
  714.      _B_r_u allows the use of remote tape drives for the archive device (via the
  715.      ----ffff option).  A remote tape drive filename has the form
  716.  
  717.           [_u_s_e_r@]_s_y_s_t_e_m:/_d_e_v/???
  718.  
  719.      where _s_y_s_t_e_m is the remote system, the optional _u_s_e_r is the login name to
  720.  
  721.  
  722.  
  723.                                                                        PPPPaaaaggggeeee 11111111
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  731.  
  732.  
  733.  
  734.      use on the remote system if different from the current user's login name,
  735.      and ////ddddeeeevvvv////???????????? is the tape drive to use (1600 BPI or 800 BPI, raw or
  736.      blocked, rewinding or non-rewinding, etc.).  In all cases, the user must
  737.      have the appropriate permissions on the remote system.  (See also the
  738.      CCCCAAAAVVVVEEEEAAAATTTTSSSS section, below.)
  739.  
  740. EEEEXXXXIIIITTTT CCCCOOOODDDDEEEESSSS
  741.      _B_r_u always returns meaningful status as follows:
  742.  
  743.           0    Normal exit, no errors or warnings.
  744.           1    Warnings (or interrupted).
  745.           2    Errors (or quit signal).
  746.  
  747. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  748.      cpio(1), rmt(1M), tar(1), attr(1), xfsdump(1).
  749.  
  750. UUUUNNNNIIIIXXXX SSSSYYYYSSSSTTTTEEEEMMMM IIIINNNNCCCCOOOOMMMMPPPPAAAATTTTIIIIBBBBIIIILLLLIIIITTTTIIIIEEEESSSS
  751.      _B_r_u recognizes special file types that may be allowed on one type of UUUUNNNNIIIIXXXX
  752.      system, but not on another.  For instance, on a 4.2 BSD system, _b_r_u will
  753.      extract fifos as plain files (mode 0666, as modified by the _u_m_a_s_k), and
  754.      issue an appropriate error message.  Usually, _b_r_u will issue two
  755.      messages.  The first message will be the more descriptive of the two.
  756.  
  757.      Currently, the only different UUUUNNNNIIIIXXXX systems that _b_r_u fully understands are
  758.      System V, 4.2 BSD, and Pyramid's OSx.
  759.  
  760. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  761.      Pathnames are limited to 127 characters in length.  This could become a
  762.      chronic problem.
  763.  
  764.      Implementation differences complicate the algorithms for automatic
  765.      detection of end of file on devices.  The algorithms can be fooled, hence
  766.      the ----ssss option.
  767.  
  768.      Special files moved to a machine other than their original host will
  769.      generally be useless and possibly even dangerous.  This goes double for
  770.      symbolic links.
  771.  
  772.      When extracting files from archives, patterns used to match directories
  773.      may result in some unnecessary directories being extracted.  For example,
  774.      if the pattern is ``a/*/c'', and the directory ``a/b'' is encountered in
  775.      the archive, the directory file ``a/b'' will be extracted since it will
  776.      be needed when (and if) the file ``a/b/c'' is encountered.  When in
  777.      doubt, use the ----wwww option.
  778.  
  779.      In order to be able to efficiently archive needed directories, _b_r_u builds
  780.      an image of the directory tree for _f_i_l_e_s using dynamically allocated
  781.      memory.  Since there may be at most 5120 characters passed on the command
  782.      line, it is very unlikely that _b_r_u will run out of memory while building
  783.      the tree from command line arguments.  This is not true of file lists
  784.      read from the standard input, particularly on machines with limited
  785.      address space.
  786.  
  787.  
  788.  
  789.                                                                        PPPPaaaaggggeeee 11112222
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796. bbbbrrrruuuu((((1111))))                                                                  bbbbrrrruuuu((((1111))))
  797.  
  798.  
  799.  
  800.      Information about file linkages is also kept in memory.  Some linkages
  801.      may be lost if memory is exhausted.
  802.  
  803.      Since _b_r_u is owned by root and runs with ``set user id'' to allow it to
  804.      create directories and special files, it makes every attempt to prevent
  805.      normal users from archiving or extracting files they would normally not
  806.      have access to.  There may be loopholes.  Also note that anyone with
  807.      physical or electronic access to an archive, and knowledge of the archive
  808.      structure, can recover any of its contents by writing their own file
  809.      extraction program.
  810.  
  811.      Files within directories which have filesystems mounted on them will not
  812.      be properly archived until the filesystem is unmounted, since the mounted
  813.      filesystem hides them.  This is not generally a problem.
  814.  
  815.      Explicitly naming both a directory and one of its descendents will cause
  816.      the descendent to be archived twice, unless they are on separate
  817.      filesystems and the ----mmmm flag is used.
  818.  
  819.      Explicitly naming a file more than once is ineffective.
  820.  
  821.      When reading from the raw magnetic tape file (rmtxxx) _b_r_u automatically
  822.      attempts to adjust the I/O buffer size to match that used to record the
  823.      archive.  Under certain circumstances it may fail and require help via
  824.      the ----bbbb option.
  825.  
  826.      Using remote tape drives can be slow.
  827.  
  828.      Extended Attributes are not archived or restored.  See _a_t_t_r(1) for more
  829.      information about Extended Attributes and see _x_f_s_d_u_m_p(1m) for a method to
  830.      back them up.
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.                                                                        PPPPaaaaggggeeee 11113333
  856.  
  857.  
  858.  
  859.